Technotools

home *** CD-ROM | disk | FTP | other *** search

/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / tcomm40 / lc.doc next >

Wrap

Text File | 1988-10-06 | 126KB | 4,621 lines

OVERVIEW OVERVIEW ________ FEATURES FEATURES ________ The LiteComm Toolbox(TM) is a set of powerful routines designed to provide easy access to the full capabilities of the PC's asynchronous communications ports. In its initial release, the LiteComm ToolBox supports fully interrupt- driven and buffered communications support on COM1 thru COM4 simultaneously. Now you can quickly incorporate sophisticated communications support in your applications without having in-depth knowledge of how the hardware functions. The ToolBox was developed as the result of a need to provide just this type of support in CAM applications which were developed for a client. Each version of the LiteComm ToolBox is heavily integrated with its respective host compiler. THE SHAREWARE CONCEPT THE SHAREWARE CONCEPT _____________________ Shareware is a "try before you buy" means of software distribution. If you find a shareware product useful, pay the registration fee, and let the authors know that you support their efforts. Information Technology, Ltd., is a member and supports the standards of, ASP, The Association of Shareware Professionals. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C LICENSE, WARRANTY AND REGISTRATION LICENSE, WARRANTY AND REGISTRATION __________________________________ LICENSE LICENSE _______ The LiteComm ToolBox, small model library only, is distributed as a shareware product. To receive all model libraries and/or the source code for the product, register your copy today. See the registration form at the end of this manual. Information Technology, Ltd, grants to registered users a non-exclusive, perpetual license to the LiteComm ToolBox, subject to these terms and conditions: 1. You must treat your copy of the LiteComm Toolbox as you would a book. You may install the LiteComm ToolBox on more than one machine, but you may use only one copy at a time. If you desire, site licenses are available at a reduced cost. You may make as many copies of the LiteComm ToolBox as you require for the sole purpose of backup. 2. You may incorporate portions of the LiteComm ToolBox in products that you develop without the payment of additional royalties or license fees. You must include the statement 'Portions Copyright 1987, 1988, Information Technology, Ltd' in your product's documentation. 3. You may copy and redistribute the shareware portion of the LiteComm ToolBox, commonly known as MCOMM.ARC and TCOMM.ARC, but you may not modify in any way, the contents of the shareware package. Further, you may not charge a fee for providing such a copy, beyond a maximum $4.00 copying or duplication fee, without the express, written consent of Information Technology, Ltd, 4. You may not redistribute, in any form, the source code for the LiteComm ToolBox. Further, you may not translate the source code for the LiteComm ToolBox into any other language without the express, written consent of Information Technology, Ltd. Page 2 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C 5. Information Technology reserves the right to change both the LiteComm ToolBox or its documentation without prior notice, with no obligation to you, the licensee. 6. You agree that any disputes arising from this license will be subject to the laws of the state of Rhode Island. 7. You agree to hold the developer and distributors of the LiteComm ToolBox harmless for any damages, either direct or consequential, that might arise from the use of this product. 8. You acknowledge that the LiteComm ToolBox, libraries, source code, and documentation are the copyrighted property of Information Technology, Ltd. 9. By your use of the LiteComm ToolBox, you acknowledge that you have read, and understand the terms and conditions of this license. WARRANTY WARRANTY ________ The LiteComm ToolBox is distributed as-is and without warranty, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Information Technology, Ltd does warrant the distribution media for a period of 30 days. During that period, Information Technology, Ltd will replace the distribution media or provide a refund at its option. Page 3 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C REGISTERING YOUR COPY REGISTERING YOUR COPY _____________________ Registration of your copy of the LiteComm ToolBox provides you with several benefits: 1. Puts you on our mailing list for low-cost updates, enhancements, and alert bulletins when they occur. 2. Gives you access to telephone support. Sorry, but we cannot provide support by telephone to unregistered user's of the ToolBox. Unregistered users can leave EMAIL on Compuserve to 70166,1152; on GEnie to I.TECH; and on DELPHI to RBMACE. We will respond to EMAIL on an as- available basis. 3.Helps to further the shareware concept. To register your copy, use the form at the end of this documentation. Page 4 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C NOTE NOTE ____ LiteComm is a package undergoing continuing development. Since its introduction, we have already delivered to registered users two protocol engines, LXM - the XMODEM engine, which supports both XMODEM and YMODEM protocols and LWXM - the Windowed XMODEM engine. Implementations of other Xmodem variants are under development. We plan to follow these with similar engines for CompuServe B, Telink, and other protocols. These engines, as they are released, will only be made available to registered ToolBox users. The small model library, as enhanced but without the protocol engines, will continue to be offered as shareware. Page 5 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C COMMUNICATIONS AND THE PC COMMUNICATIONS AND THE PC _________________________ PC SHORTCOMINGS PC SHORTCOMINGS _______________ This section is intended as a mini-tutorial on ______________________________________________ communications concepts. We encourage you to read it, _____________________________________________________ although it is not strictly necessary to do so. _______________________________________________ The IBM-PC, and its close compatibles, is a generally well thought-out, flexible, and well-executed computer. Unfortunately, not as much can be said for the thought which was given to the software which is meant to provide access to that hardware. One of the shortcomings which is most noticeable is in the support, or rather lack of it, that is provided to handle access to the serial port. Support for the serial port is limited by the BIOS to polled mode only, i.e. a program must interrogate the port on a regular basis to avoid losing received characters, and to check to determine whether or not the port is ready to send a character. Not only is this mode of operation primitive; it also tends to cause complications when attempting to perform any but the simplest of tasks, at slow speeds. A novice might think that the hardware, in some way, is the limiting factor. In fact, everything that is needed, hardware-wise, to support a more sophisticated method of handling the serial port is already there. All that is missing is the software follow-through. The LiteComm ToolBox provides this missing software. THE 8250 UART THE 8250 UART _____________ The term serial port comes from the fact that both incoming and outgoing characters entering and leaving the port do so in a bitwise fashion. When we send a character out the serial port, the responsible circuitry sends out information one bit at a time. When we receive a character, this circuitry accepts the individual bits and reassembles them into a recognizable character. These very complex operations are performed automatically by the 8250 UART (Universal Asynchronous Receiver-Transmitter). Page 6 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C The 8250 UART is a fully programmable device that permits independent control of the various parameters that affect serial communications, i.e. baud rate, parity, number of data bits, and number of stop bits. The 8250 also optionally supports four types of interrupts, error/break detection, modem status change detection, transmitter ready, and received character ready. The LiteComm ToolBox fully supports all four type of interrupts. The term asynchronous implies that there is no absolute asynchronous ____________ timing associated with the transmission of information. Instead, the clocking-in of the data bits is done by clocking-in ___________ counting the bits. The first bit sent or received is call the start bit and signals the beginning of a new character. The individual data bits follow the start bit which are clocked out and in at the specified data rate, with the least significant bit transferred first and the parity bit, if present, transferred last. Finally one or more stop bits follow, signalling the end of the character. Page 7 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C The 8250 UART takes care of all of the mechanics associated with the process described in the preceding paragraph. The UART will also detect and report error which may occur in the process. For example, if the parity bit is incorrect, the UART reports the fact. If too few or too many bits are received, the UART will report a framing error or overrun error respectively. Since the transmission of information may depend on complex interactions with another device, such as a modem or computer, the 8250 can also report on the status of the handshake lines used to provide information about the status handshake _________ of the connection with the other device. These signals are explained below. SIGNAL DESCRIPTIONS _______________________________________________________________ | | CTS Clear To Send The other device will | | accept a transmission. | | DSR Data Set Ready The other device | | is enabled. | | RI Ring Indicator Usually reserved | | for modems only. The | | phone is ringing | | DCD Carrier Detect Usually reserved for | | modems. The other modem's | | carrier signal was | | detected. | | _______________________________________________________________ | | The header file for the LiteComm ToolBox contains the various bit masks required for you to make use of the information provided by the 8250 UART. TOOLBOX NOTES AND WARNINGS TOOLBOX NOTES AND WARNINGS __________________________ Before you can send or receive information on a serial port using the ToolBox, you must use the open function to enable the line. This function initializes the 8250 UART with the correct parameters, and introduces the UART into the interrupt structure of the PC. The ToolBox will detect, and report, any errors that you may make in selecting the port or specifying the initial parameters. The ToolBox cannot and will not detect an attempt to open a non-existent serial port. Page 8 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C The ToolBox interfaces directly with the interrupt structure of the PC. It is critical that, before exiting a program that has opened a serial port that the serial port is closed with the close function. If you exit your program without closing the port, you may cause your system to crash since the interrupt vector for the port might point to a section of memory that no longer contains the needed code to support the interrupt. As an alternative, some C compilers provide a function that permits you to introduce your own routines into the normal exit() processing. Since each of these schemes has different requirements, we suggest that you consult your compiler's documentation. Page 9 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C Failure of the open function can be the result of either improper parameters to the open function, or insufficient memory available to allocate the requested buffers and related control structures for the port. Memory for the transmit and receive buffers as well as the port control block are allocated from free memory. It is your responsibility to insure that adequate memory is available for this purpose. Unless you are very familiar with the interrupt structure of the PC, do not attempt to manipulate the interrupt enable flag outside of the ToolBox. The ToolBox sets and clears the interrupt enable flag at appropriate times and assumes that it has sole control over the flag. Unless otherwise specified, all library functions have been compiled with the default structure alignment, i.e. the structure alignment switch has not been used in creating the ToolBox library. Page 10 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C RECENT CHANGES RECENT CHANGES ______________ NEW IN VERSION 2.XX NEW IN VERSION 2.XX ___________________ With version 2.0 of LiteComm, we added several new functions and made available, to registered users,the xmodem engine promised when LiteComm was first released. Version 2.1 of LiteComm further expanded upon COM3 and COM4 support by supporting interrupt chaining, permitting COM3 and COM4 to augment, rather than replace, existing interrupts. Version 2.12 was a maintenance release, and did not incorporate any new functionality. It was discovered, during the development of the Windowed XModem engine that there was a bug in the automatic XON-XOFF feature which could cause the transmit buffer to overflow under some circumstances. Version 2.12 corrected this problem. Several user-reported bugs were also corrected in 2.12.Our thanks to Jerry Wasinger for his reports of several of these problems. We also want to thank Jerry for his providing an alternate approach to handling the transmission of BREAK characters (see the lc_sbrk function).With Jerry's permission, we have based an alternate function on some of his efforts. With version 2.20, we introduced the second of out protocol engines, this one for the increasingly-popular Windowed XMODEM. As with LXM, LWXM (LiteComm Windowed XModem) is available to LiteComm registrants only. Version 2.50 marks the beginning of support for Microsoft C,version 5.0 and QuickC. In version 2.5 of the ToolBox, the original lc_sbrk function as been removed and only lc_sbrk2 is supported. For the sake of compatibility with previous versions, lc_sbrk2 has been renamed to lc_sbrk. Version 2.50 also includes a new function, lc_ocnt that returns the number of characters in the output buffer. Version 2.60 corrects a bug in the lc_gets function that has gone undetected since version 1.0. The bug was such that the function would repeatedly return the same characters, unless the requested number of characters forced a buffer wrap-around to occur. Page 11 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C Version 2.60 also enhances the capabilities of the XModem protocol engine, adding YModem support for further efficiency. Page 12 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C NEW IN VERSION 3.00 NEW IN VERSION 3.00 ___________________ Version 3.00 incorporates changes in several areas. It is with regret that, due to a lack of interest, we have been forced to drop support for the Datalight C compiler. While we feel that Datalight offers a superior product at an affordable price, the lack of registrants for this version do not justify the continued support. Additional effort has been spent on further tightening the kernel code to improve the ability of LiteComm to handle higher baud rates. Our tests indicate that sustained speeds of 38.4 Kbaud should be practical. And for added flexibility, we have made the Baud parameter used in the comm_opn and comm_setup functions infinitely variable. There is no longer the need to use the defined constants in the litecomm.h header file. Please note that to achieve these peformance improvements that the litecomm.h file has changed, requiring that you re-compile and relink any existing applications. We have added a function that should be of use to those of you that have a need to DETECT when a break signal has been received. See the documentation for lc_gotbrk, found in the section dealing with lc_sbrk. As the result of questions and difficulty for users in dealing with the lc_mstat function, the way in which the function operates has been substantially altered. Version 3.00 also corrects a bug that was recently detected in the lch_sreg function. The bug caused the intended value to be ignored, and the value of the register was being set to the register number itself. Our apologies for this oversight. Page 13 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C NEW IN VERSION 4.00 NEW IN VERSION 4.00 ___________________ With version 4.0, we have made a significant departure from the design of the previous versions. In the previous versions, with one small exception, LiteComm was written entirely in C. While the scheme was useful from the standpoint of enhancements and maintainability, it also introduced an inherent inefficiency into the interrupt handlers, limiting the baud rates that could be attained. With version 4, the critical interrupt handlers have been recoded in assembly language to expand the range of suitable baud rates. In addition, while interrupt processing is in progress, the interrupt handlers now switch to their own internal stacks, to avoid any possibility of stack overflow. In response to many questions, we have added several new functions to the LiteComm package that both serve as tutorials on how to address certain problems ('How do I tell if the phone is ringing, and how do I answer the call' for example) and are of practical use in certain applications, such as the development of a Bulletin Board. We know you will find a use for them. See the section of the BBS support functions. Page 14 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C BEYOND COM2 BEYOND COM2 ___________ THE TOOLBOX METHODOLOGY THE TOOLBOX METHODOLOGY _______________________ In the design of the original PC, and in subsequent variations such as the PC/AT, there were only provision for two serial ports. Many manufacturers of add-in products, both serial ports and internal modems have added the capability to support 1 or more additional ports beyond the COM2 limit. Generally, this can cause problems in the PC since there is no room in the interrupt request scheme for additional levels of interrupts, and there are no designated interrupt vector for other additional ports. The ToolBox approach to resolving these issues is to permit the programmer a degree of control over the parameters that govern the interrupt mechanism for COM3 and COM4. Specifically, these parameters are: 1) the interrupt request (IRQ) bit that is used to mask the 8259 interrupt controller; 2) the interrupt vector number (not address) to which the port is attached; and 3) the base i/o register for the port itself. Of course, it is assumed that the port is based upon the 8250 UART or compatible device. Before you attempt to use COM3 and/or COM4, you must determine from the port's documentation, the appropriate values for these three parameters. As distributed, the ToolBox assumes the following: COM3 COM4 ____ ____ IRQ Bit 4 3 Vector # 0Ch 0Bh Base Reg 3E8h 2E8h You may change any or all of these values by using the _portchg function described below, but only before you open the port with comm_opn. Once the port has been opened, _portchg is ineffective, and _portchg will not work on COM1 or COM2. Page 15 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C CAUTIONS CAUTIONS ________ There is an intimate relationship between the IRQ setting and the interrupt vector to which it relates. In the PC, this relationship is controlled, in part, by the 8259 interrupt controller that is set during BIOS initialization. In brief, the BIOS settings for the PC (and most close compatibles) establish IRQ0 as being vector number 08h, and subsequent IRQ levels at increasing vector numbers. These vector numbers (or types in INTEL terms) act as a cpu- directed call table to locations in the lowest 1K of system memory. We can alter how the system responds to a given interrupt by replacing or changing the values in the associated vector position to point to a routine which we supply. COM3 and COM4 share two critical parameters with COM1 and COM2 respectively, the IRQ bit and the interrupt vector number. If you intend to use COM1 with COM3 or COM2 with COM4 simultaneously, you must change the BOTH the vector number and the IRQ for COM3 or COM4 to an unused or un- needed vector. The ability for your add-on ports to handle such a change is highly hardware dependent, so check your port's documentation carefully. Failure to do so will result in loss of data at best, and a system lockup at worst. Judging from the questions asked by some users of LiteComm, there is evidently some mis-understanding about using ports beyond COM2, and how this all relates to your hardware. Before you can successfully use COM3 or COM4, you must consider the following: 1. Does the hardware permit a change to the base port and/or the interrupt vector to which the port responds. Some expansion cards will support changing one and not the other, giving rise to potential hardware conflicts and lost data. Page 16 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C 2. Does the hardware permit re-assignment of the IRQ priority. Some expansion cards permit you to alter the IRQ priority, some won't. Suffice it to say from the previous discussion the any change to the IRQ priority must allow a corresponding change to the interrupt vector number. Without this capability, reprogramming of the 8259 chip would be required. 3. In fact, many add-on cards permit this dual change simply by making a single switch or jumper setting. Unfortunately, the documentation for these cards generally assume that you are aware of the dual nature of the IRQ vector relationship, and may leave you with the impression that you are changing one and not the other. In most circumstances, this is not the case. The point to all of this is that LiteComm can only provide as much support as the hardware permits, or is capable of responding to. If you wish to use other than the default base port, interrupt vector, or irq priority for COM3 or COM4, then your expansion card must be capable of supporting the new values; in other words, these values are all hardware-provided, and are recognized by the LiteComm software. If your hardware does not permit changing a value, LiteComm cannot improve the situation. We should, at this point, add one final caution about how interrupt priorities function, and their relationship to the irq bit the you may select. The standard PC permits 8 interrupt priority levels, with the programmable timer having the highest priority, and the parallel printer port having the lowest priority. When an interrupt occurs, the interrupt controller (8259 chip) masks out all other interrupts from the priority of the interrupting device and all lower priority devices. As an aid to making COM3 and COM4 "fit", LiteComm supports interrupt chaining for the COM3 and COM4 ports. If you use COM3 or COM4, when an interrupt occurs, the kernel will attempt to determine if the interrupt was caused by the supported port or from some other source. If the kernel determines that the supported port did not cause the interrupt, an automatic chain to the original interrupt handler for that interrupt level (IRQ level) will take place, allowing you to "patch in" or share the available interrupt vectors. Page 17 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C If you intend to use other than the library-provided defaults, be sure that you understand the interrupt mechanism. The use of the automatic chaining described above can be particularly troublesome under some circumstances, resulting in loss of interrupts and, potentially, a system crash. DO NOT attempt to mix the ToolBox functions with other seemingly-related functions (such as the BIOS calls provided in both Turbo and Microsoft C). At least two users have attempted to only use the receive-portions of LiteComm, while resorting to the BIOS functions to send characters. The result at best has been failure of the user's application to function, and, at worst, total system lockups. This mix of functions is NOT supported and must not be used. If you attempt such a mix, we cannot help you. One final caution is in order. One or two users have attempted to trace through the interrupts as they occur using debuggers. This is a risky proposition at best since most debuggers work by tapping into, and disturbing, the interrupt mechanism. If you feel you must use a debugger, try to stay away from the kernel routines of LiteComm, or use a hardware-based debugger such as Periscope. Page 18 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C PACKAGE CONTENTS PACKAGE CONTENTS ________________ Your distribution diskette contains several files that are important to you. All distribution diskettes, at a minimum, include the following files in the diskette's root directory: .fo off LSERIAL.NUM SERIAL NUMBER OF THIS COPY READ.ME LATEST INFORMATION ABOUT LITECOMM TCOMM.ARC SHAREWARE VERSION AND DOCUMENTATION FILES - TURBO C VERSION MCOMM.ARC SHAREWARE VERSION AND DOCUMENTATION FILES - MICROSOFT C VERSION TCLIB.ARC ALL MODEL LIBRARIES FOR TURBO C MSCLIB.ARC ALL MODEL LIBRARIES FOR MICROSOFT C If you registered for the source code modules, the diskette contains a sub directory called SOURCE. The SOURCE directory contains 2 source code archives, as well as several compiler specific archives. LITECOMM SOURCE CODE LCSRC.ARC XMODEM ENGINE SOURCE CODE LXMSRC.ARC COMPILER SPECIFIC FILES MSC.ARC TURBOC.ARC Page 19 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C COMPILER-SPECIFIC INSTRUCTIONS COMPILER-SPECIFIC INSTRUCTIONS ______________________________ INSTALLING THE TURBO C VERSION INSTALLING THE TURBO C VERSION ______________________________ In the following discussion, we assume that your regular ________________________________________________________ Turbo header files are contained in a directory called ______________________________________________________ \TC\INCLUDE, and that your Turbo libraries are in a \TC\INCLUDE ___________________________________________________ directory called \TC\LIB, as recommended by Borland. \TC\LIB ____________________________________________________ To install the header files used with LiteComm, perform the following steps: 1. CD \TC\INCLUDE 2. ARC E A:TCOMM *.H 3. ARC E A:TCLIB *.H Page 20 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C To install the library files, perform the following steps: 1. CD \TC\LIB 2. ARC E A:TCLIB *.LIB If you are installing only the libraries, this completes the installation procedure for Turbo C. If you have registered for the package's source code, we recommend that you create two subdirectories named COMM and PROTO to hold the LiteComm and XModem source code respectively. To install the LiteComm source code, do the following: 1. MD \COMM 2. CD \COMM 3. ARC E A:LCSRC *.* To install the XModem source code, do the following: 1. MD \PROTO 2. CD \PROTO 3. ARC E A:LXMSRC *.* We strongly urge that you use the recommended approach in handling the source code to avoid naming conflicts that might arise. It is important to source code registrants to be aware that to successfully rebuild the LiteComm or XModem libraries, the supplied make files assume that you are using Turbo-C version 1.5, and therefore have access to the TLIB program that is a part of Version 1.5. If you are using version 1.0 of Turbo-C, you must have access to LIB.EXE, the MicroSoft Librarian program, or a suitable replacement. To use the make files included in the package under these circumstances, you will have to change the make files accordingly to refer to LIB rather than TLIB. Page 21 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C Turbo C users must also be aware of several additional facts. One module, ichain, is written in assembly code.To reassemble this module, you must have access to MicroSoft MASM, Version 5.0 or greater. The object version of ichain is in the TURBOC.ARC file. When you specify the use of the LiteComm and XModem Engine libraries in Turbo C, you must fully qualify the library name in your .PRJ file, even if you have specified the default library directory in the TC Option. The library option tells TC how to look for the standard Turbo C libraries, but not any user-provided libraries. INSTALLING THE MICROSOFT C VERSION INSTALLING THE MICROSOFT C VERSION __________________________________ In the following discussion, we assume that your regular ________________________________________________________ header files are contained in a sub-directory called ____________________________________________________ INCLUDE, and that your libraries are in a sub-directory INCLUDE _______________________________________________________ called LIB, as recommended by Microsoft. These instructions LIB ___________________________________________________________ pertain to both Microsoft QuickC and standard C. ________________________________________________ To install the header files used with LiteComm, perform the following steps: 1. CD INCLUDE 2. ARC E A:MCOMM *.H 3. ARC E A:MCLIB *.H To install the library files, perform the following steps: 1. CD LIB 2. ARC E A:MCLIB *.LIB Page 22 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C If you are installing only the libraries, this completes the installation procedure for Microsoft C. If you have registered for the package's source code, we recommend that you create two subdirectories named COMM and PROTO to hold the LiteComm and XModem source code respectively. To install the LiteComm source code, do the following: 1. MD COMM 2. CD COMM 3. ARC E A:LCSRC *.* To install the XModem source code, do the following: 1. MD PROTO 2. CD PROTO 3. ARC E A:LXMSRC *.* We strongly urge that you use the recommended approach in handling the source code to avoid naming conflicts that might arise. It is important to source code registrants to be aware that to successfully rebuild the LiteComm or XModem libraries, you must have access to a copy of LIB.EXE, the MicroSoft Librarian program, or a suitable replacement. To use the make files included in the package, LIB.EXE must either be in your current working directory, or in a directory specified in the DOS PATH variable. For additional information on setting the PATH variable, consult your DOS manual. Page 23 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C Microsoft C users need to know that the Microsoft C version is written in, and intended to support Microsoft C version 5.0 and QuickC. The package has not been tested with earlier versions of Microsoft C. QuickC also note that we have NOT provided a QLB version of the libraries. If you wish to create a QLB version of the libraries for use in the QuickC environment, follow the procedures outlined on pages 237-ff of the QuickC Programmer's Guide. Remember, the QuickC environment requires the MEDIUM memory model. Therefore, unregistered users cannot create a useable QLB library following this procedure. Alternatively, you can use the supplied medium model library within the QuickC environment by specifying the library as part of a program list. Unregistered QuickC users can still use QCL to create useable programs with the supplied small model library. Be sure to use the /AS switch when compiling. Page 24 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C GENERAL NOTES GENERAL NOTES _____________ The LiteComm and related libraries make extensive use of parameters defined in the included header files. Where appropriate, your programs should always use the same header file parameters. While every effort will be made in future releases of LiteComm to preserve the values as currently provided, we cannot guarantee that changes will never occur.The safest way to safeguard your efforts is to use the defined parameters. In this way, a simple recompile and relink will insure consistency from one release of LiteComm to the next. In the discussion of the various functions which follow, you should assume that any references to the port variable refer to a variable or constant that may take on a value of from 1 to 4. No other values are acceptable, and will be rejected. While we feel that LiteComm is written in the most efficient way possible, commensurate with good programming practice, we cannot be responsible for variations caused by hardware configurations or other factors beyond our control. LiteComm has been tested, and is known to perform on, the IBM PC-AT and several compatible systems such as the Zenith and Wyse equivalents. LiteComm has not been tested in environments in which other software, most significantly TSR (terminate and stay resident) modules exist. Some TSR programs that "steal" interrupts for their own purposes present an unfavorable environment to other programs that rely on the interrupt structure of the computer. Should you experience erratic behavior with LiteComm in a TSR-type situation, try executing your application without the TSR module being present. If the problems you have experienced disappear, suspect the TSR module. Conversely, LiteComm provides an excellent vehicle for supporting TSR programs that you may write. Since the package is fully reentrant, your only concern need be with those aspects of TSR programs are of normal concern, e.g. the non-reentrant nature of DOS. LiteComm never uses DOS functions and may therefore be safely used in a TSR environment. Page 25 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C Several users have reported problems in consistently detecting a ringing telephone by checking the state of the RI (Ring Indicator) signal. The problem seems to be highly dependant on the type of modem that is being used, since this signal is provided by the modem. If the duration of the signal is too short, the program may miss the signal as the modem toggles it on and off. One workaround that seems to be satisfactory is to check the RICHG bit returned from lc_mstat, rather than the RI bit. The RICHG bit will be set when the RI bit comes one and again when the RI bit goes off. This is the method employed in the new check_for_call function. Page 26 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C FUNCTION REFERENCE FUNCTION REFERENCE __________________ In the following pages, we provide the detailed information about each of the available LiteComm ToolBox functions. Each function definition includes, at a minimum, a summary of how the function is referenced, a description of what the function does, and an indication of those values, if any, that the function might perform. Where appropriate, we include additional documentation about the function. Some definitions include examples, in the sense of code fragments illustrating the function's usage. More importantly, some definitions include additional notes and warnings as well as references to other functions within the package. We have made every effort to insure that the documentation of the functions is complete and accurate. The style and manner of the documentation assumes that the reader is thoroughly familiar with the elements of C syntax and common conventions. Page 27 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ _portchg portchg _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int _portchg(port, base, irq, vector) unsigned port; unsigned base; unsigned vector; char irq; DESCRIPTION DESCRIPTION ___________ Changes one or more of the critical parameters for COM3 or COM4. This function must be used before the port is opened to be effective. To leave any of the parameters at its default value, make the corresponding entry 0. Note that vector is a vector number, not an address or pointer. The irq parameter should not be taken to be the irq (interrupt request number, but rather the irq mask. The following lines, reproduced from 'litecomm.h' help illustrate this idea. #define IRQ1 0x10 /* int req mask for port 1 - irq4 */ #define IRQ2 0x08 /* int req mask for port 2 - irq3 */ Note that the value for irq4 is NOT 4, but a character in which bit 4, using INTEL's bit numbering, is set to a value of 1. Thus, to use irq priority 1 as the irq for either COM3 or COM4, you would specify 0x02 as the value of irq when calling _portchg. The default parameters are shown in the litecomm.h include file. If you intend to change the default irq settings, you MUST also make a corresponding change to the vector number. See the accompanying documentation about using COM3 and COM4 for additional details. Failure to follow this rule may make the port appear to be non-functional. Page 28 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C The _portchg function does NOT check to determine that you have provided both an IRQ mask AND a new vector number. EXAMPLE EXAMPLE _______ if (_portchg(port, 0x408, 0, 0, 0) == -1) { printf("Error Changing Port %d\n", port); exit(1); } RETURN VALUES RETURN VALUES _____________ Returns 0 if the function is successful, -1 if you attempt to change a port other that 3 or 4. Page 29 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ comm_opn comm_opn _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int comm_opn(port, baud, parity, datab, stopb, inbufsz, outbufsz) unsigned port; unsigned baud; unsigned parity; unsigned datab; unsigned stopb; unsigned inbufsz; unsigned outbufsz; DESCRIPTION DESCRIPTION ___________ Opens the specified port for use and attaches an interrupt handler to DOS for the port. The function allocates buffers for input and output of the specified sizes, and sets the port to the parameters specified. The minimum value for inbufsz is 128; the minimum size for outbufsz is 64. A port opened in this manner must be closed using comm_close before program termination to avoid the possibility of a system crash. The baud parameter is an unsigned integer that specifies the baud rate you intend to use, e.g. 4800. The other parameters passed to the function should be from the parameter set in the litecomm.h include file. EXAMPLE EXAMPLE _______ if (comm_opn(port, 1200, NPARITY, BIT8, STOP1, 256, 256) == -1) { printf("Error Opening Port %d\n", port); exit(1); } RETURN VALUES RETURN VALUES _____________ Upon successful open, the function returns port. If any error occurs, regardless of type, the function returns -1. Page 30 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ comm_close _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int comm_close(port) unsigned port; DESCRIPTION DESCRIPTION ___________ This function is the companion to comm_opn and, in effect, performs the opposite action. Comm_close detaches the library routines from the interrupt handler, and reconnects the previous interrupt handler. Comm_close also release dynamically allocated member used for buffering and control structures. Failure to call comm_close before terminating a program may result in unexplained system crashes or hangs. RETURN VALUES RETURN VALUES _____________ If any error occurs, regardless of type, the function returns -1. Page 31 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ comm_setup _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int comm_setup(port,baud,parity,datab,stopb) unsigned port; unsigned baud; unsigned parity; unsigned datab; unsigned stopb; DESCRIPTION DESCRIPTION ___________ The comm_setup function is a subset of the comm_opn function and the remarks made in the description of comm_opn apply. This function is useful if you wish to change the basic communication parameters of the specified port that has already been opened without comm_close'ing the port and breaking the telephone connection. EXAMPLE EXAMPLE _______ if (comm_setup(port, 1200, NPARITY, BIT8, STOP1) == -1) { printf("Error Changing Port %d\n", port); exit(1); } RETURN VALUES RETURN VALUES _____________ If any error occurs, regardless of type, the function returns -1. SEE ALSO SEE ALSO ________ comm_opn Page 32 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_vport _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> COMM *lc_vport(port) unsigned port; DESCRIPTION DESCRIPTION ___________ Used internally to validate that the port number specified is correct and has been opened with the comm_opn function. May be of use to you in writing certain applications. RETURN VALUES RETURN VALUES _____________ If the port is valid and has been opened, returns a pointer to the control block for the port. Returns NULL if an error occurs; Page 33 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_icnt _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_icnt(port) int lc_ocnt(port) unsigned port; DESCRIPTION DESCRIPTION ___________ May be used to determine the number of characters currently in the input(lc_icnt) or output(lc_ocnt) buffers for the port. RETURN VALUES RETURN VALUES _____________ Both functions return -1 if an error occurs (port not open or invalid port number).The lc_icnt() function return the number of characters in the input buffer; lc_ocnt() returns the number of characters in the transmit buffer that have not been sent. Page 34 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_mstat _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_mstat(port) unsigned port; DESCRIPTION DESCRIPTION ___________ May be used to determine the last known state of the modem- supplied handshake signals. These may be tested using the values in the include'd litecomm.h file. The handshake signals consist of a byte in which the bits 4-7 contain the current state of the signals (such as Clear To Send or CTS) and bits 0-3 contain information regarding whether or not individual signals have changed. lc_mstat always returns the current values of signals in bits 4-7. Bits 0-3 will reflect which, if any, of the signals has changed. The easiest approach to dealing with the returned value is to test bits 0-3 for a non-zero value. If any non-zero value is returned, one or more signals have changed since the last call to lc_mstat. NOTE: You should be aware that the bits 0-3 are reset once this function is called. The value obtained from bits 4-7 will correctly reflect the current state of the signals. To determine which signals, if any, have changed use the XXXCHG bits returned (see litecomm.h). RETURN VALUES RETURN VALUES _____________ If the port is valid and has been opened, returns the current modem status bits. Returns -1 if an error occurs. Page 35 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_estat _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_estat(port) unsigned port; DESCRIPTION DESCRIPTION ___________ May be used to determine the last known state of the serial port's error status bits. These may be tested using the values in the include'd litecomm.h file. RETURN VALUES RETURN VALUES _____________ If the port is valid and has been opened, returns the current error status bits. Returns -1 if an error occurs. Page 36 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_getw _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_getw(port) unsigned port; DESCRIPTION DESCRIPTION ___________ Read a character from the serial port's input buffer. Wait indefinitely until a character is available. RETURN VALUES RETURN VALUES _____________ Returns the next available character in the input buffer for the port. Returns -1 if the port is not active. Page 37 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_setmdm _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_setmdm(port, newset) unsigned port; unsigned newset; DESCRIPTION DESCRIPTION ___________ Set one or more of the modem control signals. Because of the need to always have OUT2 set for interrupt support, the function always provides the correct setting for this bit. Use the mask values found in the include file. RETURN VALUES RETURN VALUES _____________ Returns 0 if the operation was successful, returns -1 otherwise. SEE ALSO SEE ALSO ________ lc_clrmdm, lc_togmdm Page 38 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_clrmdm _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_clrmdm(port, newset) unsigned port; unsigned newset; DESCRIPTION DESCRIPTION ___________ Companion to setmdm function. Clears one or more of the modem control signals. Because of the need to always have OUT2 set for interrupt support, the function always provides the correct setting for this bit. Use the mask values found in the include file. RETURN VALUES RETURN VALUES _____________ Returns 0 if the operation was successful, returns -1 otherwise. SEE ALSO SEE ALSO ________ lc_setmdm, lc_togmdm Page 39 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_togmdm _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_togmdm(port, newset) unsigned port; unsigned newset; DESCRIPTION DESCRIPTION ___________ Companion to setmdm function. Flip-flops one or more of the modem control signals. Because of the need to always have OUT2 set for interrupt support, the function always provides the correct setting for this bit. Use the mask values found in the include file. RETURN VALUES RETURN VALUES _____________ Returns 0 if the operation was successful, returns -1 otherwise. SEE ALSO SEE ALSO ________ lc_setmdm, lc_clrmdm Page 40 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_xoff _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_xoff(port, flag) unsigned port; BOOL flag; /* #define BOOL int */ DESCRIPTION DESCRIPTION ___________ If flag is TRUE, turns on semi-automatic XON-XOFF flow control function. If flag is FALSE (the default setting), automatic flow control is disabled. When enabled, the kernel will automatically transmit an XOFF if and when the input buffer is approximately 2/3 full and will automatically recognize an XOFF sent by the companion system. If the companion system transmits an XOFF, the kernel will refuse to send any characters until the condition is cleared. It is the programmer's responsibility to transmit XON when conditions permit. See the lc_putxoff function to tell if an automatic XOFF has been sent by the kernel. See the lc_gotxoff function to determine if the kernel has detected an XOFF. If you intended to implement a protocol that might include the XON-XOFF characters, be sure to disable the automatic flow control. Failure to do so may result in a system hang. RETURN VALUES RETURN VALUES _____________ Returns 0 if the operation was successful, returns -1 otherwise. SEE ALSO SEE ALSO ________ lc_gotxoff, lc_putxoff Page 41 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_gotxoff _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> BOOL lc_gotxoff(port) unsigned port; /* #define BOOL int */ DESCRIPTION DESCRIPTION ___________ See below for the values returned. If an XOFF has been received, the port's flag will be reset, and transmission to the companion system will be permitted. If an XON is received from the companion system, the port's flag will also be reset, permitting further transmissions to occur. Be aware that if the companion system never sends an XON after sending an XOFF, a possible race condition may occur, race ____ resulting in a system hang. RETURN VALUES RETURN VALUES _____________ Returns TRUE if an XOFF was detected, FALSE if an XOFF was not detected. Will return -1 in the case of an error. SEE ALSO SEE ALSO ________ lc_xoff, lc_putxoff Page 42 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_putxoff _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> BOOL lc_putxoff(port) unsigned port; /* #define BOOL int */ DESCRIPTION DESCRIPTION ___________ See below for the values returned. If an XOFF has been sent, the port's flag will be reset. Use this function in concert with transmission of an XON character to the companion system to permit transmissions to proceed. RETURN VALUES RETURN VALUES _____________ Returns TRUE if XOFF was sent to the companion system, FALSE if XOFF not sent since the last time the function was called. Will return -1 in the case of an error. SEE ALSO SEE ALSO ________ lc_xoff, lc_putxoff Page 43 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_get _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_get(port) unsigned port; DESCRIPTION DESCRIPTION ___________ Read a character from the serial port's input buffer. RETURN VALUES RETURN VALUES _____________ Returns the next available character in the input buffer for the port. Returns -1 if the port is not active, or if there are not characters in the port's buffer. Page 44 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_peek _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_peek(port) unsigned port; DESCRIPTION DESCRIPTION ___________ Look at the next character in the serial port's input buffer. RETURN VALUES RETURN VALUES _____________ Returns the next available character in the input buffer for the port, but does not remove the character from the buffer. This allows the application to look-ahead by one character look-ahead __________ in a non-destructive fashion. Returns -1 if the port is not active, or if there are no characters in the port's buffer. Page 45 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_put _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_put(port,ch) unsigned port; char ch; DESCRIPTION DESCRIPTION ___________ Place a character into the serial port's output buffer. RETURN VALUES RETURN VALUES _____________ Returns 0 if successful. Note that this does not guarantee that the character has been sent, only that no errors were detected. Returns -1 if the port is not active, or if there no room in the port's buffer. Page 46 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_gets _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_gets(port, buff, cnt) unsigned port; char *buff; int cnt; DESCRIPTION DESCRIPTION ___________ Read a stream of, at most, cnt characters from the serial port's input buffer into the buff location. Not sensitive to NULL character. RETURN VALUES RETURN VALUES _____________ Returns the count of characters actually transferred, or -1 if an error occurs. Page 47 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_puts _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_puts(port, buff, cnt) unsigned port; char *buff; int cnt; DESCRIPTION DESCRIPTION ___________ Place a stream of, at most,cnt characters into the serial cnt ___ port's output buffer. RETURN VALUES RETURN VALUES _____________ Returns the number of characters actually placed into the buffer. Note that this does not guarantee that the characters have been sent. Returns 0 if any error occurs, or if there no room in the port's buffer. Page 48 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_flush _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_tflush(port) int lc_rflush(port) int lc_flshtrue(port, ch) int lc_nflush(port, cnt) unsigned port; char ch; int cnt; DESCRIPTION DESCRIPTION ___________ The <?>flush functions remove characters from the specified buffer and discard them; untransmitted characters in the transmit buffer are NEVER sent; unprocessed characters in the receive buffer are lost. lc_tflush empties the port's transmit buffer immediately. lc_rflush empties the port's receive buffer immediately. lc_flshtrue will continually dispose of received characters until the character ch is received. Use caution with this one since it does not detect port number errors. lc_nflush flushes, at most, cnt characters from the port's receive buffer. RETURN VALUES RETURN VALUES _____________ lc_flshtrue returns no values. lc_tflush and lc_rflush return 0 if successful and -1 if an error occurs. lc_nflush returns the number of characters actually flushed from the receive buffer or 0 in the case of no characters to flush, or if an error was detected an error. Page 49 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_sbrk _______________________________________________________________ SUMMARY SUMMARY _______ #include <litecomm.h> int lc_sbrk(port) lc_gotbrk(port) unsigned port; DESCRIPTION DESCRIPTION ___________ lc_sbrk() generates a BREAK signal using a particular characteristic of the 8250 UART to generate a more accurate BREAK at any baud rate. BREAKS generated in this manner are timed based upon the baud rate at which the 8250 is currently initialized. This function may or may not work correctly with other than the actual 8250 UART. lc_gotbrk returns TRUE if a break signal has been received on the specified port. It returns FALSE otherwise. RETURN VALUES RETURN VALUES _____________ Returns 0 if successful. Returns -1 if the port is not active. Page 50 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ BBS SUPPORT FUNCTIONS _______________________________________________________________ INTRODUCTION INTRODUCTION ____________ In this section, we discuss a set of utility functions that were originally developed as a part of a new, and as yet unannounced BBS package in conjunction with one of our registered users. Not only are they useful, in and of themselves, but they also act as examples of using the LiteComm ToolBox in situations that puzzle some users. Page 51 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ new_event _______________________________________________________________ SUMMARY SUMMARY _______ include "lcbbs.h"; long new_event(sec); int check_event(evtimer); unsinged sec; long evtimer; DESCRIPTION DESCRIPTION ___________ The new_event function creates an 'event timer' that will expire in sec seconds. This function relies upon the calculation of an absolute time value, based upon current date and time, and does not tie into any system intterupt, permitting as many independant time-out timers as required by your application. The check_event function examines the contents of an event timer created by new_event with respect to the current date and time, and indicates whether or not the timer has expired. Do not attempt to use check_event against a variable that was not set by new_event. If you do so, the results are unpreditaable and may result in a seeming system hang. RETURN VALUES RETURN VALUES _____________ The new_event function returns a value that represents a point in time sec from the time that new_event was called. The check_event function returns a non-zero (TRUE) value if the specified event timer has expired, a value of zero (0) otherwise. Page 52 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C EXAMPLE EXAMPLE _______ long cdtimer; cdtimer = new_event(30); /* 30 second timer */ while( ! check_event(cdtimer)) if (check_for_call(port) > 0) { cprintf("Incoming call\r\n"); return(1); } cprintf("No calls in 30 seconds\r\n"); return(0); Page 53 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ check_for_call _______________________________________________________________ SUMMARY SUMMARY _______ include "lcbbs.h"; int check_for_call(port) unsigned port; DESCRIPTION DESCRIPTION ___________ This function checks the status of the specified port to determine whether or not 1) there is an incoming call and 2) waits for up to 30 seconds for carrier to be established with the caller if the phone rang. Please note that this function relies upon, in part, the HAYES command set. Use with other than HAYES-compatible modems may result in uxpected hangs or other, unpredictable results. The function assumes that the modem parameters have been set in the manner described in the reset_modem function. In the event that a wrong number call is received, check_for_call will automatically disconnect by lowering the DTR(Data Terminal Ready) signal momentarily, then automatically call the reset_modem function. This disconnect method, while absolute, will only work correctly if you HAVE NOT set your modem to ignore the DTR signals, as is possible with some modems. Please consult your modem's documentation for additional detail. RETURN VALUES RETURN VALUES _____________ If the phone was not ringing, the function return a value of zero. If a ring was detected, but carrier was not detected withing 30 seconds,, the function will return a value of -1 after forcing a disconnect and resetting the modem. Otherwise, the numeric result code, in integer form, is returned. It is the programmer's responsibility to interpret and act upon the result code. For the function to work properly, the modem must be set to return numeric result codes rather than word result codes. Page 54 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ get_modem_reply _______________________________________________________________ SUMMARY SUMMARY _______ include "lcbbs.h" int get_modem_reply(port) unsigned port; DESCRIPTION DESCRIPTION ___________ The get_modem_reply function is intended for use after a command has been issued to a HAYES compatible modem. To operate properly, the modem must be set to return numeric responses rather than word responses. The function returns to the caller when one of the following occurs: 1) no response from the modem within 1 second; 2) more than 2 response characters received before a <CR> is detected; or 3) a <CR> is received from the modem. Due to the internal logic employed, the programmer should call this function, or purge the receive buffer after each command sent to the modem. Failure to do so will result in improper interpretation of the result codes returned. RETURN VALUES RETURN VALUES _____________ Returns a value of -1 if no response from the modem is detected within 1 second. Otherwise returns the integer result code. If the modem has not been set to return numeric result codes, the results are unpredictable. Page 55 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ reset_modem _______________________________________________________________ SUMMARY SUMMARY _______ include "lcbbs.h" int reset_modem(port) unsigned port; DESCRIPTION DESCRIPTION ___________ The reset_modem function initializes the modem to a known state, suitable for use with the other bbs functions. The condition set includes tuch tone dialing, detect carrier, numeric result codes, HAYES extended command set, answer the phone on the first ring, and enbale the speaker while dialing. If you require any additional information on these or related options, please consult your modem's documentation. RETURN VALUES RETURN VALUES _____________ The reset_modem function returns the same result code as those specified for get_modem_reply. Page 56 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ disconnect _______________________________________________________________ SUMMARY SUMMARY _______ include "lcbbs.h" void disconnect(port) unsigned port; DESCRIPTION DESCRIPTION ___________ The disconnect forceably disconnects the modem from the telephone line by lowering the DTR signal momentarily. You must be certain that your modem IS NOT set to ignore the DTR signal for the function to work properly. RETURN VALUES RETURN VALUES _____________ Disconnect returns no values. Page 57 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ HAYES MODEM FUNCTIONS; _______________________________________________________________ Note - When using the following functions, you must include ___________________________________________________________ the file litehcm.h in your program. litehcm.h automatically ___________________________________________________________ includes the litecomm.h header file. ____________________________________ FUNCTIONS FUNCTIONS _________ lch_codeset lch_dial lch_fduplex lch_hduplex lch_greg lch_sreg lch_offcarr lch_oncarr lch_offecho lch_onecho lch_hook lch_redo lch_numres lch_wrdres lch_codesoff lch_codeson lch_pulse lch_tone lch_speaker _retset _rettype Page 58 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C SUMMARY SUMMARY _______ #include <litehcm.h> int lch_codeset(port,mode) int lch_dial(port,dstr) int lch_fduplex(port) int lch_hduplex(port) int lch_greg(port,reg) int lch_sreg(port,reg,value) int lch_offcarr(port) int lch_oncarr(port) int lch_offecho(port) int lch_onecho(port) int lch_hook(port,hmode) int lch_redo(port) int lch_numres(port) int lch_wrdres(port) int lch_codesoff(port) int lch_codeson(port) int lch_pulse(port) int lch_tone(port) int lch_speaker(port,spkmode) int _retset() int _rettype() unsigned port; unsigned mode; char *dstr; unsigned reg; int value; unsigned hmode; unsigned spkmode; Page 59 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C DESCRIPTION DESCRIPTION ___________ The values to be used in conjunction with mode, hmode, and spkmode are defined in the #include-d file litehcm.h. The lch_codeset function allows you to change the set of codes that are returned by the modem when an action is specified. lch_dial instructs the modem to dial the number contained in dstr. Do not include the dialing (ATD) prefix, or the trailing <CR>. These are provided by the function. You may include non-numeric characters as the contents of dstr are not checked. The dialing is done in the last known, pulse or tone, mode. If you use the lch_pulse or lch_tone functions, then dialing will be done in the mode that was last correctly enabled. If you have not exercised these functions, then dialing occurs in the modems default or power-up mode. The lch_hduplex and lch_fduplex functions place the modem into local echo and remote echo modes respectively. The lch_greg function requests that the modem report the current value of S-register reg. Reg must be in the range 0 to 13. Use the lch_gets, or similar function, to retrieve the modem's response. Specifying a register outside the 0 to 13 range will cause a return of -1. lch_sreg is the companion to lch_greg, with the same restrictions. Sets the S-register reg to the value contained in value. If value contains -1, then the register is reset to its default (power-up) value. The function checks the value to be certain that it is within the limits specified for the particular register, and returns a value of -1 if the value is outside the predefined limits. lch_offcarr enables modem carrier detect, but disables the modems carrier signal. The lch_oncarr companion enables both carrier detect and the modems carrier signal. When lch_offcarr is used the modem will receive data but will be unable to send data. Page 60 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C The lch_offecho and lch_onecho functions determine whether commands sent to the modem are echoed back to the sending program. With echo turned off, the modem will continue to accept commands, but will not try to redisplay the command's characters. lch_hook allows you to control the current status of the modem's telephone line connection. See your modem's documentation and the include file for additional information. The lch_redo function instructs the modem to repeat the last command sequence executed. Generally, this function is of greatest value in re-dialing numbers that are busy, although its use is not restricted to that. Page 61 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C The way in which your modem responds to commands is determined, in part by the lch_wrdres and lch_numres functions. If you call lch_wrdres, then modem responses use the English language response codes, e.g. CONNECT or OK. Calling lch_numres instructs the modem to respond with code numbers only from the currently selected response set, see the lch_codeset function above. You may use the functions lch_codeson and lch_codesoff to specify whether you want your modem to send back response codes when it receives a command string. In a sense, these act as companions to the lch_xxxecho functions above. Use the lch_speaker function to control the modem's internal speaker, if it has one. See litehcm.h for the applicable codes. The _retset and _rettype functions return, respectively, the last known command set (lch_codeset) and last known result type (lch_wrdres, lch_numres). These functions (_retset, _rettype) are only of value when used in conjunction with the companion functions. Page 62 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C GENERAL REMARKS GENERAL REMARKS _______________ Several considerations are in order if you intend to use the Hayes ToolBox functions. 1. You are responsible for checking the return codes from the modem once you have given modem a command. To make the task easier, we suggest that you turn OFF command echo (so that you don't have to worry about separating commands from responses) and turn ON numeric responses (to make the interpretation of result codes easier and faster). 2. Be sure that you allow adequate time between commands for the modem to process the command and respond. Failure to observe this rule may result in commands being misinterpreted or "lost". You can monitor the number of characters in the receive buffer to help you with the timing. Or alternatively, check the response after each command. The latter approach is more in line with what we believe to be good programming practice. RETURN VALUES RETURN VALUES _____________ All functions return a value of -1 if a port or other error is detected, zero otherwise. Page 63 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C MISCELLANEOUS FUNCTIONS MISCELLANEOUS FUNCTIONS _______________________ These additional functions, while part of the LiteComm These additional functions, while part of the LiteComm ______________________________________________________ library, are intended for use with LXM, the xmodem engine. library, are intended for use with LXM, the xmodem engine. __________________________________________________________ _______________________________________________________________ lc_insclock _______________________________________________________________ SUMMARY SUMMARY _______ #include <lctime.h> int lc_insclock() /* install programmable timer */ void lc_clrclock() /* remove programmable timer */ DESCRIPTION DESCRIPTION ___________ Install the programmable interval timer at interrupt vector 0x1C, if not already installed. You must use this function before attempting to access any of the other functions in this set. In addition, Datalight users must, upon termination of their program, reset the vector by using the lc_clrclock function. Turbo C and Microsoft C users need to know that the an exit() function is installed to automatically replace the vector by calling lc_clrclock. RETURN VALUES RETURN VALUES _____________ lc_insclock always returns 0, lc_clrclock never returns a value. Page 64 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C _______________________________________________________________ lc_setclock _______________________________________________________________ SUMMARY SUMMARY _______ #include <lctime.h> void lc_setclock(secs) unsigned secs; DESCRIPTION DESCRIPTION ___________ Sets the programmable timer to the number of seconds specified in secs. The amount of time remaining on the clock, in seconds, can be examined in the _secs_rem variable, defined in lctime.h. _secs_rem will never decrease below a value of zero. RETURN VALUES RETURN VALUES _____________ lc_setclock never returns a value. Page 65 CopyRight (c) 1987, 1988 Information Technology, Ltd. LITECOMM (TM) COMMUNICATIONS TOOLBOX for Microsoft and Turbo C Page 66 CopyRight (c) 1987, 1988 Information Technology, Ltd. REGISTRATION FORM REGISTRATION FORM _________________ Please complete the following information. Note that the prices below are for a single-use registration only. Please contact us directly for site licensing. Mail to: Information Technology PO Box 554 Coventry, RI 02816 Telephone Orders or Information (401) 826-2223 ┌──────────────────────────────────────────────────────────┐ │ SHIP TO: │ │ Name ________________________________________ │ │ │ │ Company ________________________________________ │ │ │ │ Street ________________________________________ │ │ │ │ ________________________________________ │ │ │ │ City ___________________ State __ Zip _____ │ │ │ │ Telephone _______________________ │ ├─────┬──────────┬───────────────────┬─────────────────────┤ │ │ │ │ │ │ QTY │ COMPILER │ REGISTRATION TYPE │ REGISTRATION FEE │ │ │ │ │ │ ├─────┼──────────┼───────────────────┼─────────────────────┤ │ │ │ │ │ │ │ │ LIBRARIES @ $25 │ │ │ │ │ │ │ ├─────┼──────────┼───────────────────┼─────────────────────┤ │ │ │ │ │ │ │ │ LIBRARIES AND │ │ │ │ │ SOURCE @ $50 │ │ │ │ │ │ │ ├─────┼──────────┼───────────────────┼─────────────────────┤ │ │ │ 3.5 " Disk ? $1.00│ │ │ │ │ │ │ │ │ │ RI Sales Tax 6% │ │ └─────┴──────────┴───────────────────┴─────────────────────┘ Method of Payment (Check, Mastercard, Visa) _____________ Credit Card Number __________________________ Expiration Date __________________________ Name as it appears on card ___________________________ Signature for MC/VISA ________________________________ All MasterCard/Visa orders must include a telephone number, We regret that we cannot accept COD orders _______________________________________________________________ (office use only) Date Received ______________ Date Sent _____________ Version ______________ Serial Number _______________ OVERVIEW........................................... 1 FEATURES....................................... 1 THE SHAREWARE CONCEPT.......................... 1 LICENSE, WARRANTY AND REGISTRATION................. 2 LICENSE........................................ 2 WARRANTY....................................... 3 REGISTERING YOUR COPY.......................... 4 NOTE........................................... 5 COMMUNICATIONS AND THE PC.......................... 6 PC SHORTCOMINGS................................ 6 THE 8250 UART.................................. 6 SIGNAL DESCRIPTIONS............................ 8 TOOLBOX NOTES AND WARNINGS......................... 8 RECENT CHANGES..................................... 11 NEW IN VERSION 2.XX............................ 11 NEW IN VERSION 3.00............................ 13 NEW IN VERSION 4.00............................ 14 BEYOND COM2........................................ 15 THE TOOLBOX METHODOLOGY........................ 15 CAUTIONS....................................... 16 PACKAGE CONTENTS................................... 19 COMPILER-SPECIFIC INSTRUCTIONS..................... 20 INSTALLING THE TURBO C VERSION................. 20 INSTALLING THE MICROSOFT C VERSION............. 22 GENERAL NOTES.................................. 25 FUNCTION REFERENCE................................. 27 BBS SUPPORT FUNCTIONS.............................. 51 HAYES MODEM FUNCTIONS.............................. 58 GENERAL REMARKS................................ 63 MISCELLANEOUS FUNCTIONS............................ 64 REGISTRATION FORM.................................. 67 8250 6, 8 lch_fduplex 58 8259 15 lch_greg 58 _portchg 15 lch_hduplex 58 _secs_rem 65 lch_hook 58 Asynchronous 7 lch_numres 58 BIOS 6, 16 lch_offcarr 58 Bit number 28 lch_offecho 58 BREAK 50 lch_oncarr 58 Buffers 10, 30 lch_onecho 58 Clocking-in 7 lch_pulse 58 COM3 16, 28 lch_redo 58 COM4 16, 28 lch_speaker 58 Control block 10 lch_sreg 58 Dialing 60 lch_tone 58 DTR 54, 57 lch_wrdres 58 Event timer 52 Interrupt enable flag 10 Flow control 41 Interrupt request 15 Functions Interrupt vector 15 _portchg 28 Interrupts 7 check_for_call 54 IRQ 16 comm_close 31 Memory 10 comm_opn 30 Numeric result code 54 comm_setup 32 Port 25 disconnect 57 S-register 60 get_modem_reply 55 Serial port 6 lc_clrmdm 39 Start bit 7 lc_estat 36 Stop bits 7 lc_flush 49 Structure alignment 10 lc_get 44 TSR 25 lc_gets 47 XOFF 41, 42, 43 lc_getw 37 XON 41, 42, 43 lc_gotbrk(port) unsigned port 50 lc_gotxoff 42 lc_icnt 34 lc_insclock 64 lc_mstat 35 lc_ocnt 34 lc_peek 45 lc_put 46 lc_puts 48 lc_putxoff 43 lc_sbrk 50 lc_setclock 65 lc_setmdm 38 lc_togmdm 40 lc_vport 33 lc_xoff 41 new_event 52 reset_modem 56 Handshake 8 HAYES 54, 55, 56 Hayes Functions _retset 58 _rettype 58 lch_codeset 58 lch_codesoff 58 lch_codeson 58 lch_dial 58 1